.NET Debugging : Introduction to the Tools - SOS & SOSEX

SOS

SOS is a debugger extension that can be used to debug .NET applications using the native debuggers. It provides a truly amazing set of commands that enables developers to delve deep into the CLR and help troubleshoot pesky application bugs. Among other things, there are commands that enable you to see the finalization queues, managed heaps, managed threads, setting managed code breakpoints, seeing exceptions, and much more.

Because SOS provides an abstracted view into the internals of the CLR, it’s important to note that when debugging using the SOS debugger extension, care must be taken to use the correct version of SOS. Each of the .NET versions ship with its corresponding version of SOS and can be found in the following location:

%windir%\microsoft.net\<architecture>\<version>\sos.dll

Architecture can be either Framework (for 32-bit) or Framework64 (for 64-bit), and the version represents the version of the .NET framework you are targeting.

Before the SOS debugger extension can be used, it must be loaded into the debugger by using the .load command. Listing 1 illustrates the loading process when running notepad.exe under the debugger.

Listing 1. Loading the SOS debugger extension command

0:000> .load c:\Windows\Microsoft.NET\Framework\v2.0.50727\SOS.dll
0:000>! help
------------------------------------------------------------------------------
SOS is a debugger extension DLL designed to aid in the debugging of managed
programs. Functions are listed by category, then roughly in order of
importance. Shortcut names for popular functions are listed in parenthesis.
Type "!help <functionname>" for detailed info on that function.
Object Inspection                     Examining code and stacks
-------------------------             ---------------------------
DumpObj (do)                          Threads
DumpArray (da)                        CLRStack
DumpStackObjects (dso)                IP2MD
DumpHeap                              U
DumpVC                                DumpStack
GCRoot                                EEStack
ObjSize                               GCInfo
FinalizeQueue                         EHInfo
PrintException (pe)                   COMState
TraverseHeap                          BPMD


Examining CLR data structures         Diagnostic Utilities
-------------------------             ---------------------------
DumpDomain                            VerifyHeap
EEHeap                                DumpLog
Name2EE                               FindAppDomain
SyncBlk                               SaveModule
DumpMT                                GCHandles
DumpClass                             GCHandleLeaks
DumpMD                                VMMap
Token2EE                              VMStat
EEVersion                             ProcInfo
DumpModule                            StopOnException (soe)
ThreadPool                            MinidumpMode
DumpAssembly
DumpMethodSig                         Other
DumpRuntimeTypes                      ---------------------------
DumpSig                               FAQ
RCWCleanupList
DumpIL
0:000> !Threads
Failed to find runtime DLL (mscorwks.dll), 0x80004005
Extension commands need mscorwks.dll in order to have something to do.
0:000>

					  

In Listing 1, we started by loading the 2.0 version of the SOS debugger extension. Following a successful load, we issued the !help extension command that displayed a list of available commands from the SOS extension. Next, we attempted to use the !threads command to display all the managed threads in the process. The net result was an error that stated that mscorwks.dll could not be found. When a .NET application is first loaded, the CLR is also loaded and initialized. The primary library responsible for the runtime functionality is mscorwks.dll. If the runtime is not found in the process being debugged, SOS returns an error essentially indicating that the process is not a .NET process or that the runtime has not been loaded yet and hence the debugger extension commands will not be available.

To avoid specifying the full path to the SOS debugger extension, the .loadby debugger command can be utilized. The syntax of the .loadby command is as follows:

.loadby <extension DLL> <module name>

The extension DLL represents the name of the debugger extension we want to load (such as SOS.DLL) and the module name represents a currently loaded module (such as mscorwks.dll). The .loadby command then attempts to load the extension DLL from the same path that the module is located in. For example, to load the SOS extension from the same directory in which mscorwks.dll is located, the following command can be used:

.loadby SOS.dll mscorwks

One final note on SOS is that it can be loaded and used in Visual Studio 2008 by using the .load sos command in an intermediate window.

SOSEX

SOSEX is another debugger extension targeted at the native debuggers and managed code debugging. It was developed by Steve Johnson and is available as a free download. SOSEX, not surprisingly, stands for SOS Extended. SOSEX adds a set of powerful debugging commands to your arsenal. Examples of such commands include deadlock detection, generational garbage collection commands, and more powerful breakpoint commands.

The installation of SOSEX comes in the form of a ZIP file. Simply extract the files contained in the ZIP file to a location of choice. I typically place extensions in the folder where the debuggers are installed to avoid having to specify full paths when loading the extension. Once loaded, you can begin using the commands as shown in Listing 2.

Listing 2. Loading the SOSEX debugger extension command

0:000> .load sosex.dll
0:000> !sosex.help
SOSEX - Copyright 2007-2008 by Steve Johnson - http://www.stevestechspot.com/
Quick Ref:
-------------------------------------------------------
dumpgen <decGenNum> [-stat] [-type <TYPE_NAME>]
gcgen   <hexObjectAddr>
refs    <hexObjectAddr>
bpsc    <strSourceFile> <decLineNum> [decColNum]
bpmo    <strTypeName> <strMethodName> <hexILOffset>
vars    [decFrameNum|-w]
date    <hexDateAddr>
isf     <strTypeName> <strFieldName>
dlk

Use !help <command> for more details about each command.
0:000>